在介紹欄位之前，今天想要介紹如何幫我們套件裡的 function 增加提示說明，會運用到 function typing 跟 function 的 docstrings 的功用與如何撰寫。

Function Typing

Docstrings 是指當在使用套件的 function 的時候，透過滑鼠移動到 import 的 function 的時候，系統會有文字提示，以 pybaseball 的 statcast function 當作例子：

讓他先跟我們在 Day 09 - 簡單上傳一版到 TestPyPI 寫得簡單 function hello 做比較：

可以看到，在 hello 的提示裡，在 parameters 裡面的 name，就只有顯示他的參數名稱，而不是像 statcast 寫的 start_dt: str=None。少的這些分別表示，start_dt 需要傳入 str 型態（Type），然後預設會是 None，這在我們寫 function 的時候加入，例如 hello function 可以寫成這樣：

def hello(name: str = "LH"):
    print(f"Hello {name}! Welcome to baseball-stats-python")

結果就會變成這樣：

但發現還少了 ->，這個符號的意思會是 function 最後回傳的數值的 type，像是 statcast 就會是會回傳 pd.DataFrame 的意思。要加這個提示一樣就照著寫：

def hello(name: str = "LH") -> None:
    print(f"Hello {name}! Welcome to baseball-stats-python")

因為 hello 最後是只有執行 print 沒有任何回傳值，所以設定提示為 -> None，改完結果會變成：

不過要提醒一件事，因為 Python 沒有支援 runtime 的 type checking，所以這些設定都只是提示在使用 function 會出現的提示，如果我們傳入不同的 type，不會特別回傳錯誤，這點要特別注意。

Function Docstrings

另一個 statcast 跟 hello 不一樣的地方，是 statcast 下面一段文字敘述，要有這個就需要使用 Docstrings。要增加的方法就是在宣告 function 的 def 下面用三個引號 """ 把敘述包起來，例如我們把 hello 增加：

def hello(name: str) -> None:
    """
    Prints a greeting to the user.
    """
    print(f"Hello {name}! Welcome to baseball-stats-python")

就能看到提示下面會多一行文字：

這樣就能完成說明附加，不過通常我們在說明 function，會再多說明 function 的 arguments 跟 return，讓使用者可以得到更多有用的資訊，例如：

def hello(name: str) -> None:
    """
    Prints a greeting to the user.

    Args:
        name (str): The user's name.

    Returns:
        None
    """
    print(f"Hello {name}! Welcome to baseball-stats-python")

有時候需要傳入的 arguments 會有多種值，也可以在裡面說明。

本日小結

今天介紹如何幫我們的套件增加說明，再次提醒目前這些設定都只有提示的效果，不會真的在 runtime 幫我們偵測到使用錯誤的型別，但這些說明在之後釋出給其他人使用套件的時候，就能有效地提供說明，讓他們能更快瞭解使用的 function，跟應該傳入什麼樣的數值，這不只在 Open Source 的開發，大家在工作的時候開發也能幫助的其他工程師。明天沒意外應該會真的來介紹常用的欄位了，希望大家會喜歡。

最後一樣感謝大家耐心地看完這篇文章，有任何建議與問題都歡迎在留言告訴我，明天見，掰掰。